/*
 * Created by Christopher King
 * Copyright (C) 2007 Christopher King, All Rights Reserved.
 */

package us.cirion.adventure.engine;

/**
 * A Noun is a physical item in the game. It could be a person, an apple, or a
 * table. Nouns will form the basis for most games, and a player's interaction
 * with various nouns will advance the plot of the game.
 * 
 * @author Chris
 */
public class Noun extends Word
{

	private StringBuffer description;
	private String shortText;
	private ItemLocation location;

	/**
	 * Retrieves a short textual description of the noun. Short text is
	 * appropriate when displaying a brief label or other truncated form of
	 * text.
	 * 
	 * @return A string with a short description of the noun.
	 */
	public String getShortText()
	{
		return shortText;
	}

	/**
	 * Sets a short textual description of the noun. The description should
	 * include only a few words and be complete, legible, and brief.
	 * 
	 * @param shortText The short description of the noun.
	 */
	public void setShortText(String shortText)
	{
		this.shortText = shortText;
	}

	/**
	 * Retrieves a description of the item. For example, if a noun has the name
	 * "Apple", the description might be "a small and red apple.
	 * 
	 * @return A description of this noun.
	 */
	public StringBuffer getDescription()
	{
		return description;
	}

	/**
	 * Sets a description of the item. The description can be of any length, but
	 * should only include the noun, not a complete sentence. For example, "a
	 * small and red apple" is a valid description, but "it is a small and red
	 * apple" is not.
	 * 
	 * @param description A description of the item.
	 */
	public void setDescription(StringBuffer description)
	{
		this.description = description;
	}

	/**
	 * Reports the current location of the item.
	 * 
	 * @return The current location of the item.
	 */
	public ItemLocation getLocation()
	{
		return location;
	}

	/**
	 * Retrieves human-readable, but brief, name of the noun.
	 * 
	 * @return Human-readable text describing the noun.
	 */
	public String getDisplayText()
	{
		return shortText;
	}

	/**
	 * Places this item in the specified location. If this item used to be
	 * somewhere else, it will be removed from that location.
	 * 
	 * @param location The new location for this item.
	 */
	public void setLocation(ItemLocation location)
	{
		ItemLocation oldLocation = this.location;
		this.location = location;
		// If this used to be somewhere else, it's gone now.
		if (oldLocation != null)
		{
			if (location.equals(oldLocation))
			{
				// Already here!
				return;
			}
			oldLocation.removeItem(this);
		}
		// Notify the room that it now holds this as well.
		if (!location.containsItem(this))
		{
			location.addItem(this);
		}
		this.location = location;
	}

}
